Inside Macintosh: Open Transport /

Chapter 3 - Endpoints / Endpoints Reference

Functions / Creating Endpoints

OTAsyncOpenEndpoint

Opens an endpoint and installs a notifier callback function for the endpoint.

The OTAsyncOpenEndpoint function is asynchronous, and creates an endpoint that operates asynchronously.

C INTERFACE

OSStatus OTAsyncOpenEndpoint (OTConfiguration* config, 
                              OTOpenFlags oflag, 
                              TEndpointInfo* info, 
                              OTNotifyProcPtr proc, 
                              void* contextPtr);

C++ INTERFACE

None. C++ applications use the C interface to this function.

PARAMETERS

config

A pointer to an endpoint configuration structure that specifies the endpoint's characteristics. You obtain a value for the config parameter by calling the OTCreateConfiguration function.

oflag

Reserved; must be set to 0.

info

A pointer to a TEndpointInfo structure to be filled in by the OTAsyncOpenEndpoint function. Specify NULL for this parameter if you do not want the OTAsyncOpenEndpoint function to return endpoint information.

proc

A pointer to a notifier callback function for this endpoint. If you do not provide a notifier function, your application cannot receive completion events, including the event advising you that the endpoint has been created. Specify NULL for this parameter if you do not want to provide a notifier function. In this case, you can use the OTLook function to poll for asynchronous events (but not for completion events).

contextPtr

A pointer for your use. The endpoint provider passes this pointer value when calling the notifier function you specify in the proc parameter. You might use the contextPtr parameter, for example, to pass to your notifier function information about your application's current context.

DESCRIPTION

The OTAsyncOpenEndpoint function opens an endpoint having the characteristics specified by the config parameter. The OTAsyncOpenEndpoint function runs asynchronously, returning a result code as soon as the function has been queued for execution. How processing proceeds then depends on this result code.

If the result code is any except kOTNoError, an error occurred and Open Transport does not queue the function for execution. The OTAsyncOpenEndpoint function creates no endpoint and does not call the notifier function that you specified in the proc parameter.

If the result code is kOTNoError, the OTAsyncOpenEndpoint function attempts to create an endpoint. Then it calls the notifier function that you specified in the proc parameter, passing T_OPENCOMPLETE for the code parameter, a result code in the result parameter, and the endpoint reference for the newly created endpoint in the cookie parameter. It is recommended that you use the OTAsyncOpenEndpoint function to install a notifier function rather than using the OTInstallNotifier function to do it.

An endpoint created by the OTAsyncOpenEndpoint function operates in asynchronous mode, unless you change the endpoint's mode of execution by calling the OTSetSynchronous function. When an endpoint is in asynchronous mode, all provider functions that use the endpoint execute asynchronously.

By default, a newly created endpoint does not block and does not acknowledge sends. To change the endpoint's default mode of operation, you can call the OTSetBlocking function and the OTIsAckingSends function.

The preliminary state of an endpoint is T_UNBND, meaning that the endpoint is not bound to a protocol address. Before using the endpoint to transfer data, you must bind it to a protocol address by calling the OTBind function.

SPECIAL CONSIDERATIONS

The OTAsyncOpenEndpoint function destroys the configuration structure returned by the OTCreateConfiguration function. If you want to use the same configuration to open additional endpoints, you must obtain a valid copy of the configuration structure by calling the OTCloneConfiguration function before you call the OTAsyncOpenEndpoint function.

COMPLETION EVENT CODES

T_OPENCOMPLETE

0x20000007

The OTAsyncOpenEndpoint function has completed. The cookie parameter of the notifier function points to the endpoint reference for the new endpoint.

SEE ALSO

To create an OTConfiguration structure, use the OTCreateConfiguration function described in the chapter "Configuration Management" in this book.

To obtain a copy of the OTConfiguration structure, use the OTCloneConfiguration function described in the chapter "Configuration Management" in this book.

When you open an endpoint, Open Transport also creates the TEndpointInfo structure, which contains important information about the endpoint (page 3-48).

To create an endpoint synchronously, call the OTOpenEndpoint function (page 3-74).

You can use the OTLook function (page 3-85) to poll for asynchronous events.

Modes of execution are defined in the section "Modes of Operation," beginning on page 3-11. For information about changing an endpoint's mode of execution, see the chapter "Providers" in this book.

For information about notifier functions, see the chapter "Providers" in
this book.

Endpoint states are defined and listed in"Endpoint States," beginning on page 3-13.

To close and delete an endpoint, call the OTCloseProvider function described in the chapter "Providers" in this book.

To bind a protocol address to an endpoint, call the OTBind function (page 3-77).

The OTSetAsync, OTSetBlocking, and OTIsAckingSends functions are described in the chapter "Providers" in this book.